Reference: serializeProc

serializeProc creates an opaque, POD ("plain 'old data") structure containing the filter's current configuration.

Prototype

int serializeProc(FilterActivation *fa, const FilterFunctions *ff, char *buf, int maxbuf);

Parameters:
    fa        Pointer to filter activation structure
    ff        Pointer to callback function structure
    buf       Memory block to serialize into.  May be NULL if maxbuf=0.
    maxbuf    Size of memory block in bytes.

Return value:
    The size of the memory block used, or if not enough space is available,
    the number of bytes required.

Exceptions:
    Except*() functions may be called from this function.

Requirements:
    Function is required if filter data structure contains non-serializable
    elements (pointers, OS handles, etc).  If filter data structure is already
    POD, function may be omitted -- it will be used as the serialized
    configuration.

    If the function is omitted, the filter is considered to be non-suspendable.

Host support:
    Supported in API V8, but not used by VirtualDub 1.4.11.

Remarks

This function exists for future expansion in order to support serialization of large-scale configuration data to disk. It is intended that serializeProc and deserializeProc functions can be used in lieu of script commands, but there is an important difference -- a filter may be serialized while it is active. These functions thus form a way for a host to suspend a filter in progress, saving its state to disk so that it may be resumed later. A filter does not need to serialize buffers in the filter activation record, as this is done by the host.

Typically, the host will call this function twice, once with a size of zero in order to obtain the total size, and then again with the proper memory buffer size. It is acceptable for a filter implementation to serialize twice into a temporary memory buffer during this process, copying the temporary buffer to the host buffer on the second call.

[up] back to main page


VirtualDub external filter SDK 1.05©1999-2001 Avery Lee <phaeron@virtualdub.org>